home *** CD-ROM | disk | FTP | other *** search
IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) NNNNAAAAMMMMEEEE IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222 - Introduction to matrix-vector linear algebra subprograms IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN See individual man pages for operating system and hardware availability. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The Level 2 Basic Linear Algebra Subprograms (Level 2 BLAS) consist of routines that perform matrix-vector operations. These routines are written to run optimally on all SGI systems. The following data types are used in these routines: * Single precision: Fortran "real" data type, C/C++ "float" data type, 32-bit floating point; these routine names begin with SSSS. * Single precision complex: Fortran "complex" data type, C/C++ "scsl_complex" data type (defined in <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>>), C++ STL "complex<float>" data type (defined in <<<<ccccoooommmmpppplllleeeexxxx....hhhh>), two 32-bit floating point reals; these routine names begin with CCCC. * Double precision: Fortran "double precision" data type, C/C++ "double" data type, 64-bit floating point; these routine names begin with DDDD. * Double precision complex: Fortran "double complex" data type, C/C++ "scsl_zomplex" data type (defined in <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>>), C++ STL "complex<double>" data type (defined in <<<<ccccoooommmmpppplllleeeexxxx....hhhh>>>>), two 64-bit floating point doubles; these routine names begin with ZZZZ. Often little or no difference exists between these versions, other than the data types of some inputs and outputs. In this case, the routines are described on the same man page, and that man page is named after the single precision or single precision complex routine. NOTE: SCSL supports two different C interfaces to the BLAS: * The C interface described in this man page and in individual BLAS man pages follows the same conventions used for the C interface to the SCSL signal processing library. * SCSL also supports the C interface to the legacy BLAS set forth by the BLAS Technical Forum. This interface supports row-major storage of multidimensional arrays; see IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS(3S) for details. By default, the integer arguments are 4 bytes (32 bits) in size; this is the size obtained when one links to the SCSL library with ----llllssssccccssss or ----llllssssccccssss____mmmmpppp. Another version of SCSL is available, however, in which integers are 8 bytes (64 bits). This version allows the user access to larger memory sizes and helps when porting legacy Cray codes. It can be loaded by using either the ----llllssssccccssss____iiii8888 or ----llllssssccccssss____iiii8888____mmmmpppp link option. Note that any program may use only one of the two versions; 4-byte integer and PPPPaaaaggggeeee 1111 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) 8-byte integer library calls cannot be mixed. C/C++ function prototypes for Level 2 BLAS routines are provided in <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>>, when using the default 4-byte integers, and <<<<ssssccccssssllll____bbbbllllaaaassss____iiii8888....hhhh>>>>, when using 8-byte integers. These header files define the complex types ssssccccssssllll____ccccoooommmmpppplllleeeexxxx and ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx, which are used in the prototypes. Alternatively, C++ programs may declare arguments using the types ccccoooommmmpppplllleeeexxxx<<<<ffffllllooooaaaatttt>>>> and ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> from the standard template library. But if these types are used, <<<<ccccoooommmmpppplllleeeexxxx....hhhh>>>> must be included before <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>> (or <<<<ssssccccssssllll____bbbbllllaaaassss____iiii8888....hhhh>>>>). Note, though, that both complex types are equivalent: they simply represent (real, imaginary) pairs of floating point numbers stored contiguously in memory. With the proper casts, you can simply pass arrays of floating point data to the routines where complex arguments are expected. Casts, however, can be avoided. The header files <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>> and <<<<ssssccccssssllll____bbbbllllaaaassss____iiii8888....hhhh>>>> directly support the use of user-defined complex types or disabling prototype checking for complex arguments completely. By defining the symbol SSSSCCCCSSSSLLLL____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS before including <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>> or <<<<ssssccccssssllll____bbbbllllaaaassss____iiii8888....hhhh>>>> all complex arguments will be prototyped as vvvvooooiiiidddd ****. To define the symbol SSSSCCCCSSSSLLLL____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS at compile time use the ----DDDD compiler option (i.e., ----DDDDSSSSCCCCSSSSLLLL____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS) or use an explicit ####ddddeeeeffffiiiinnnneeee SSSSCCCCSSSSLLLL____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS in the source code. This allows the use of any complex data structure without warnings from the compiler, provided the structure is as described above; that is: 1. The real and imaginary components must be contiguous in memory. 2. Sequential array elements must also be contiguous in memory. While this allows the use of non-standard complex types without generating compiler warnings, it has the disadvantage that the compiler will not catch type mismatches. Strong type checking can be enabled employing user-defined complex types instead of SCSL's standard complex types. To do this, define SSSSCCCCSSSSLLLL____UUUUSSSSEEEERRRR____CCCCOOOOMMMMPPPPLLLLEEEEXXXX____TTTT====_m_y__c_o_m_p_l_e_x and SSSSCCCCSSSSLLLL____UUUUSSSSEEEERRRR____ZZZZOOOOMMMMPPPPLLLLEEEEXXXX____TTTT====_m_y__z_o_m_p_l_e_x, where _m_y__c_o_m_p_l_e_x and _m_y__z_o_m_p_l_e_x are the names of user-defined complex types. These complex types must be defined before including the <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>> (or <<<<ssssccccssssllll____bbbbllllaaaassss____iiii8888....hhhh>>>>) header file. Fortran 90 users on IRIX systems can perform compile-time checking of SCSL BLAS subroutine and function calls by adding UUUUSSSSEEEE SSSSCCCCSSSSLLLL____BBBBLLLLAAAASSSS (for 4- byte integer arguments) or UUUUSSSSEEEE SSSSCCCCSSSSLLLL____BBBBLLLLAAAASSSS____IIII8888 (for 8-byte integer arguments) to the source code from which the BLAS calls are made. Alternatively, the compile-time checking can be invoked without any source code modifications by using the ----aaaauuuuttttoooo____uuuusssseeee compiler option, e.g., f90 -auto_use SCSL_BLAS test.f -lscs f90 -auto_use SCSL_BLAS_I8 -i8 test.f -lscs_i8 PPPPaaaaggggeeee 2222 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) AAAArrrrrrrraaaayyyy SSSSttttoooorrrraaaaggggeeee Multidimensional arrays passed as arguments to BLAS routines must be stored in column-major order, the storage convention used in Fortran programs. C and C++ users must explicitly store multidimensional arrays column-by-column. One way to do this is to reverse the order of array dimensions with respect to the Fortran declaration (e.g., xxxx((((llllddddxxxx,,,,nnnn)))) in Fortran versus xxxx[[[[nnnn]]]][[[[llllddddxxxx]]]] in C/C++). Because of the prototypes used in <<<<ssssccccssssllll____bbbbllllaaaassss....hhhh>>>>, the array should be cast as a pointer to the appropriate type when passed as an argument to a BLAS routine in order to avoid potential compiler type mismatch errors or warning messages. C and C++ users who want to employ row-major storage for multidimensional arrays when calling the BLAS routines should consult the IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS(3S) man page. IIIInnnnccccrrrreeeemmmmeeeennnntttt aaaarrrrgggguuuummmmeeeennnnttttssss A vector's description consists of the name of the array (_x or _y) followed by the storage spacing (increment) in the array of vector elements (_i_n_c_x or _i_n_c_y). The increment can be positive or negative. When a vector _x consists of _n elements, the corresponding actual array arguments must be of a length at least 1111++++((((nnnn----1111))))****||||iiiinnnnccccxxxx||||. For a negative increment, the first element of _x is assumed to be xxxx((((1111++++((((nnnn----1111))))****||||iiiinnnnccccxxxx||||)))) for Fortran arrays, xxxx[[[[((((nnnn----1111))))****||||iiiinnnnccccxxxx||||]]]] for C/C++ arrays. MMMMaaaannnn ppppaaaaggggeeee nnnnaaaammmmiiiinnnngggg The mmmmaaaannnn(1) command can find a man page online by either the single precision, single precision complex, double precision, or double precision complex name. The following table describes the naming conventions for these routines: ------------------------------------------------------------- Single Double Single Double Precision Precision Precision Precision Complex Complex ------------------------------------------------------------- form: Sname Dname Cname Zname example: SGEMM DGEMM CGEMM ZGEMM ------------------------------------------------------------- LLLLiiiisssstttt ooooffff LLLLeeeevvvveeeellll 2222 BBBBLLLLAAAASSSS rrrroooouuuuttttiiiinnnneeeessss The following list describes these routines. The list is in alphabetic order, except that each _H_e_r_m_i_t_i_a_n matrix routine (any routine whose name begins with CCCCHHHH) is grouped next to equivalent _s_y_m_m_e_t_r_i_c matrix routines (whose names begin with SSSSSSSS or CCCCSSSS). This is because the Hermitian property is a type of symmetry. Each routine marked with an asterisk (*) is an extension to the standard set of Level 2 BLAS routines. PPPPaaaaggggeeee 3333 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) * CCCCHHHHBBBBMMMMVVVV, ZZZZHHHHBBBBMMMMVVVV: Multiplies a complex vector by a complex Hermitian band matrix. y <- alpha Ax + beta y * CCCCHHHHEEEEMMMMVVVV, ZZZZHHHHEEEEMMMMVVVV: Multiplies a complex vector by a complex Hermitian matrix. y <- alpha Ax + beta y * CCCCHHHHEEEERRRR, ZZZZHHHHEEEERRRR: Performs Hermitian rank 1 update of a complex Hermitian matrix. H A <- alpha xx + A * CCCCHHHHEEEERRRR2222, ZZZZHHHHEEEERRRR2222: Performs Hermitian rank 2 update of a complex Hermitian matrix. H _____ H A <- alpha xy + alpha yx + A * CCCCHHHHPPPPMMMMVVVV, ZZZZHHHHPPPPMMMMVVVV: Multiplies a complex vector by a packed complex Hermitian matrix. y <- alpha Ax + beta y * CCCCHHHHPPPPRRRR, ZZZZHHHHPPPPRRRR: Performs Hermitian rank 1 update of a packed complex Hermitian matrix. H A <- alpha xx + A * CCCCHHHHPPPPRRRR2222, ZZZZHHHHPPPPRRRR2222: Performs Hermitian rank 2 update of a packed complex Hermitian matrix. H _____ H A <- alpha xy + alpha yx + A * SSSSGGGGBBBBMMMMVVVV, DDDDGGGGBBBBMMMMVVVV, CCCCGGGGBBBBMMMMVVVV, ZZZZGGGGBBBBMMMMVVVV: Multiplies a real or complex vector by a real or complex general band matrix. y <- alpha op(A) x + beta y where PPPPaaaaggggeeee 4444 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) op(A) = A or T op(A) = A or H op(A) = A (CGBMV, ZGBMV only) * SSSSGGGGEEEEMMMMVVVV, DDDDGGGGEEEEMMMMVVVV, CCCCGGGGEEEEMMMMVVVV, ZZZZGGGGEEEEMMMMVVVV: Multiplies a real or complex vector by a real or complex general matrix. y <- alpha op(A) x + beta y where op(A) = A or T op(A) = A or H op(A) = A (CGEMV, ZGEMV only) * SSSSGGGGEEEERRRR, DDDDGGGGEEEERRRR: Performs rank 1 update of a real general matrix. T A <- alpha xy + A * CCCCGGGGEEEERRRRCCCC, ZZZZGGGGEEEERRRRCCCC: Performs conjugated rank 1 update of a complex general matrix. H A <- alpha xy + A * CCCCGGGGEEEERRRRUUUU, ZZZZGGGGEEEERRRRUUUU: Performs unconjugated rank 1 update of a complex general matrix. T A <- alpha xy + A PPPPaaaaggggeeee 5555 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) * SSSSGGGGEEEESSSSUUUUMMMM*, DDDDGGGGEEEESSSSUUUUMMMM*, CCCCGGGGEEEESSSSUUUUMMMM*, ZZZZGGGGEEEESSSSUUUUMMMM*: Adds a scalar multiple of a real or complex matrix to a scalar multiple of another real or complex matrix. B <- alpha op(A) + beta B where op(A) = A or T op(A) = A or H op(A) = A (CGESUM, ZGESUM only) * SSSSSSSSBBBBMMMMVVVV, DDDDSSSSBBBBMMMMVVVV: Multiplies a real vector by a real symmetric band matrix. y <- alpha Ax + beta y * SSSSSSSSPPPPMMMMVVVV, DDDDSSSSPPPPMMMMVVVV, CCCCSSSSPPPPMMMMVVVV****, ZZZZSSSSPPPPMMMMVVVV****: Multiplies a real or complex vector by a real or complex symmetric packed matrix. y <- alpha Ax + beta y * SSSSSSSSPPPPRRRR, DDDDSSSSPPPPRRRR, CCCCSSSSPPPPRRRR****, ZZZZSSSSPPPPRRRR****: Performs symmetric rank 1 update of a real or complex symmetric packed matrix. T A <- alpha xx + A * SSSSSSSSPPPPRRRR2222, DDDDSSSSPPPPRRRR2222: Performs symmetric rank 2 update of a real symmetric packed matrix. T T A <- alpha xy + alpha yx + A * SSSSSSSSYYYYMMMMVVVV, DDDDSSSSYYYYMMMMVVVV, CCCCSSSSYYYYMMMMVVVV****, ZZZZSSSSYYYYMMMMVVVV****: Multiplies a real or complex vector by a real or complex symmetric matrix. y <- alpha Ax + beta y PPPPaaaaggggeeee 6666 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) * SSSSSSSSYYYYRRRR, DDDDSSSSYYYYRRRR, CCCCSSSSYYYYRRRR*, ZZZZSSSSYYYYRRRR*: Performs symmetric rank 1 update of a real or complex symmetric matrix. T A <- alpha xx + A * SSSSSSSSYYYYRRRR2222, DDDDSSSSYYYYRRRR2222: Performs symmetric rank 2 update of a real symmetric matrix. T T A <- alpha xy + alpha yx + A * SSSSTTTTBBBBMMMMVVVV, DDDDTTTTBBBBMMMMVVVV, CCCCTTTTBBBBMMMMVVVV, ZZZZTTTTBBBBMMMMVVVV: Multiplies a real or complex vector by a real or complex triangular band matrix. x <- op(A) where op(A) = A or T op(A) = A or H op(A) = A (CTBMV, ZTBMV only) * SSSSTTTTBBBBSSSSVVVV, DDDDTTTTBBBBSSSSVVVV, CCCCTTTTBBBBSSSSVVVV, ZZZZTTTTBBBBSSSSVVVV: Solves a real or complex triangular band system of equations. -1 x <- op(A)x where op(A) = A or T op(A) = A or PPPPaaaaggggeeee 7777 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) H op(A) = A (CTBSV, ZTBSV only) * SSSSTTTTPPPPMMMMVVVV, DDDDTTTTPPPPMMMMVVVV, CCCCTTTTPPPPMMMMVVVV, ZZZZTTTTPPPPMMMMVVVV: Multiplies a real or complex vector by a real or complex triangular packed matrix. x <- op(A) where op(A) = A or T op(A) = A or H op(A) = A (CTPMV, ZTPMV only) * SSSSTTTTPPPPSSSSVVVV, DDDDTTTTPPPPSSSSVVVV, CCCCTTTTPPPPSSSSVVVV, ZZZZTTTTPPPPSSSSVVVV: Solves a real or complex triangular packed system of equations. -1 x <- op(A) where op(A) = A or T op(A) = A or H op(A) = A (CTPSV. ZTPSV only) * SSSSTTTTRRRRMMMMVVVV, DDDDTTTTRRRRMMMMVVVV, CCCCTTTTRRRRMMMMVVVV, ZZZZTTTTRRRRMMMMVVVV: Multiplies a real or complex vector by a real or complex triangular matrix. x <- op(A) where PPPPaaaaggggeeee 8888 IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222((((3333SSSS)))) op(A) = A or T op(A) = A or H op(A) = A (CTRMV, ZTRMV only) * SSSSTTTTRRRRSSSSVVVV, DDDDTTTTRRRRSSSSVVVV, CCCCTTTTRRRRSSSSVVVV, ZZZZTTTTRRRRSSSSVVVV: Solves a real or complex triangular system of equations. -1 x <- op(A) where op(A) = A or T op(A) = A or H op(A) = A (CTRSV, ZTRSV only) NNNNOOOOTTTTEEEESSSS SCSL does not currently support reshaped arrays. SSSSEEEEEEEE AAAALLLLSSSSOOOO Dongarra, J., J. Du Croz, S. Hammarling, and R. Hanson, "An Extended Set of FORTRAN Basic Linear Algebra Subprograms," _A_C_M _T_r_a_n_s_a_c_t_i_o_n_s _o_n _M_a_t_h_e_m_a_t_i_c_a_l _S_o_f_t_w_a_r_e, Vol. 14, No. 1, March 1988, pp. 1 - 17. IIIINNNNTTTTRRRROOOO____SSSSCCCCSSSSLLLL(3S), IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS1111(3S), IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS3333(3S), IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS(3S) PPPPaaaaggggeeee 9999 
